<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Go OTel 应用逻辑解释 - 名词解释</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
<h1>名词解释 (Glossary)</h1>

<nav>
    <ul>
        <li><a href="index.html">概述</a></li>
        <li><a href="setup.html">初始化设置</a></li>
        <li><a href="handlers.html">HTTP 处理器</a></li>
        <li><a href="services.html">业务逻辑服务</a></li>
        <li><a href="main_flow.html">主程序流程</a></li>
        <li><a href="glossary.html" class="active">名词解释</a></li>
    </ul>
</nav>

<section>
    <dl>
        <dt>OpenTelemetry (OTel)</dt>
        <dd>一个开源的可观测性框架，用于生成、收集和导出遥测数据（追踪、指标、日志）。它提供了一套标准的 API 和 SDK，帮助开发者理解软件的性能和行为。核心目标是实现厂商无关的可观测性。</dd>

        <dt>Trace (追踪)</dt>
        <dd>代表一个请求在分布式系统中所经过的完整路径。一个 Trace 由一个或多个 Span 组成，它们共享同一个 Trace ID。</dd>

        <dt>Span (跨度)</dt>
        <dd>代表 Trace 中的一个工作单元或操作。例如，一次 HTTP 请求处理、一次数据库查询、一次函数调用都可以是一个 Span。每个 Span 有自己的 ID、开始和结束时间、名称、属性 (Attributes)、事件 (Events) 和状态 (Status)。Span 之间通过父子关系连接起来。</dd>

        <dt>Context (上下文)</dt>
        <dd>在 Go 中，<code>context.Context</code> 用于在 API 边界（如 Goroutine 或函数调用）之间传递请求范围的值、取消信号和截止时间。在 OTel 中，Context 被用来<span class="highlight">隐式地携带当前的 Trace 和 Span 信息</span>。这就是为什么我们需要在函数调用链中一直传递 <code>ctx</code>。</dd>

        <dt>Context Propagation (上下文传播)</dt>
        <dd>将追踪上下文信息（如 Trace ID 和 Span ID）从一个服务或进程传递到另一个服务或进程的过程。通常通过 HTTP Headers (如 <code>traceparent</code>) 或其他消息协议的元数据来完成。OTel Propagator 负责这个任务的编码和解码。</dd>

        <dt>TracerProvider (追踪提供者)</dt>
        <dd>OTel SDK 的一部分，负责创建 Tracer 实例，并管理 Span 的处理（采样、导出）和资源信息。</dd>

        <dt>Tracer (追踪器)</dt>
        <dd>通过 <code>otel.Tracer("...")</code> 获取的实例，用于手动创建新的 Span (<code>tracer.Start(...)</code>)。</dd>

        <dt>Attribute (属性)</dt>
        <dd>附加到 Span 上的键值对信息，用于描述 Span 的细节。例如 <code>http.method="GET"</code>, <code>db.statement="SELECT * FROM users"</code>。使用 <code>go.opentelemetry.io/otel/attribute</code> 包创建。</dd>

        <dt>Event (事件)</dt>
        <dd>附加到 Span 上的带时间戳的日志信息，用于记录 Span 生命周期内发生的特定时刻点。例如 "Cache Hit", "Starting Database Query"。</dd>

        <dt>Status (状态)</dt>
        <dd>表示 Span 代表的操作是否成功完成。通常有三种状态：<code>Unset</code> (默认), <code>Ok</code> (成功), <code>Error</code> (失败)。</dd>

        <dt>Schema URL</dt>
        <dd>一个 URL，标识了 OTel 资源属性和语义约定所遵循的规范版本。用于确保不同版本的 OTel SDK 或库之间能正确理解遥测数据的含义。</dd>

        <dt>Semantic Conventions (语义约定)</dt>
        <dd>OTel 定义的一套标准化的属性键名（例如 <code>http.method</code>, <code>db.system</code>, <code>service.name</code>），用于确保不同工具和系统能够一致地理解和处理遥测数据。代码中通过导入 <code>go.opentelemetry.io/otel/semconv/...</code> 包来使用这些标准键。</dd>

        <dt>Instrumentation (插桩)</dt>
        <dd>将 OTel 代码（用于创建 Span、记录属性等）集成到应用程序或库代码中的过程。可以是手动的（开发者显式调用 OTel API），也可以是自动的（通过库或中间件自动完成）。</dd>

        <dt>Gin</dt>
        <dd>一个用 Go 编写的高性能 Web 框架，用于快速构建 Web 应用和 API。它提供了路由、中间件、请求绑定、响应渲染等功能。</dd>

        <dt>Middleware (中间件)</dt>
        <dd>在 Gin (或其他 Web 框架) 中，中间件是处理 HTTP 请求/响应链的一部分。它可以在请求到达最终处理函数之前或之后执行一些通用逻辑，如日志记录、认证、Panic 恢复、以及 OTel 追踪（如 <code>otelgin</code>）。</dd>

        <dt>GORM</dt>
        <dd>Go 语言中一个流行的对象关系映射 (ORM) 库。它简化了与关系型数据库（如 MySQL, PostgreSQL）的交互，允许开发者使用 Go 结构体来操作数据库表。</dd>

        <dt>ORM (Object-Relational Mapping)</dt>
        <dd>对象关系映射，一种编程技术，用于在面向对象编程语言（如 Go）中的对象和关系型数据库中的表之间建立映射关系。开发者可以操作对象，ORM 负责将其转换为相应的 SQL 语句。</dd>

        <dt>Redis</dt>
        <dd>一个开源的、内存中的数据结构存储系统，通常用作缓存、消息代理和数据库。以其高性能而闻名。</dd>

        <dt>Cache (缓存)</dt>
        <dd>一种存储技术，用于临时保存经常访问的数据，以便更快地检索，减少对较慢后端系统（如数据库）的访问压力，从而提高性能和响应速度。Redis 在这个应用中被用作缓存。</dd>

        <dt>UUID (Universally Unique Identifier)</dt>
        <dd>通用唯一标识符。一个 128 位的数字，用于在计算机系统中唯一地标识信息。在这个应用中，它被用来生成用户 ID。</dd>

        <dt>DSN (Data Source Name)</dt>
        <dd>数据源名称。一个字符串，包含了连接到特定数据库所需的所有信息，如用户名、密码、主机地址、端口、数据库名以及其他驱动程序特定的参数。</dd>

        <dt>Goroutine</dt>
        <dd>Go 语言中的一种轻量级线程，由 Go 运行时管理。可以非常高效地创建成千上万个 Goroutine 来实现并发。<code>go func() { ... }()</code> 语法就是启动一个新的 Goroutine。</dd>

        <dt>Graceful Shutdown (优雅关闭)</dt>
        <dd>指应用程序在收到终止信号时，不是立即退出，而是先停止接受新的工作（如新的 HTTP 请求），然后等待当前正在处理的工作完成后，再清理资源（如关闭数据库连接、导出追踪数据），最后才退出的过程。这可以防止数据丢失或处理中断。</dd>

        <dt>otelgin</dt>
        <dd>OpenTelemetry 为 Gin 框架提供的官方<span class="highlight">中间件</span>。它会自动处理传入请求的追踪上下文传播，为每个请求创建服务器端 Span，并记录 HTTP 相关的属性。</dd>

        <dt>otelgorm</dt>
        <dd>一个社区提供的 OpenTelemetry <span class="highlight">插件</span>，用于 GORM。通过 <code>db.Use(...)</code> 集成后，它会自动为 GORM 的数据库操作创建 Span。</dd>

        <dt>redisotel</dt>
        <dd><code>go-redis/v9</code> 库自带的 OpenTelemetry <span class="highlight">插桩</span>。通过 <code>redisotel.InstrumentTracing(...)</code> 应用后，Redis 客户端的所有命令操作都会自动创建 Span。</dd>

    </dl>
</section>

</body>
</html>